---
title: "MCP Servers"
description: "Learn how to configure and manage MCP server instances in MetaMCP"
---

A **MCP Server** is a configuration that tells MetaMCP how to start and manage a Model Context Protocol server. These servers provide tools, resources, and prompts that can be aggregated and exposed through MetaMCP endpoints.

## What is a MCP Server?

MCP Servers are the building blocks of MetaMCP. Each server configuration defines:

- **How to start the server** (command, arguments, environment)
- **What type of server it is** (STDIO, SSE, Streamable HTTP)
- **Authentication requirements** (if any)
- **Resource dependencies** (Python packages, Node modules, etc.)

<Card title="Example Configuration" icon="code">
```json
{
  "name": "HackerNews",
  "type": "STDIO", 
  "command": "uvx",
  "args": ["mcp-hn"],
  "description": "Access HackerNews stories and comments"
}
```
</Card>

## Server Types

MetaMCP supports three types of MCP servers:

<AccordionGroup>
  <Accordion icon="terminal" title="STDIO Servers">
    **Most common type** - Communicates via standard input/output streams
    
    ```json
    {
      "type": "STDIO",
      "command": "uvx", 
      "args": ["mcp-server-package"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
    ```
    
    **Use cases:**
    - Python packages installed via `uvx`
    - Node.js packages via `npx`
    - Custom executable scripts
  </Accordion>

  <Accordion icon="globe" title="SSE Servers">
    **Server-Sent Events** - Communicates via SSE (Server-Sent Events)
    
    ```json
    {
      "type": "SSE",
      "url": "https://api.example.com/sse",
      "bearerToken": "your-bearer-token"
    }
    ```

    <Info>You can leave bearerToken as blank if the server uses OAuth.</Info>
  </Accordion>

  <Accordion icon="globe" title="Streamable HTTP Servers">
    **HTTP-based streaming** - Streamable HTTP is now the standard for remote MCP
    
    ```json
    {
      "type": "STREAMABLE_HTTP",
      "url": "https://api.example.com/mcp",
      "bearerToken": "your-bearer-token"
    }
    ```

    <Info>You can leave bearerToken as blank if the server uses OAuth.</Info>
  </Accordion>
</AccordionGroup>

## Configuration Options

### Basic Configuration

<CodeGroup>
```json Required Fields
{
  "name": "unique-server-name",
  "type": "STDIO|SSE|STREAMABLE_HTTP",
  "command": "command-to-run", // STDIO only
  "args": ["arg1", "arg2"],     // STDIO only
  "url": "https://...",         // SSE/STREAMABLE_HTTP only
}
```

```json Optional Fields
{
  "description": "Human-readable description",
  "env": {
    "KEY": "value"
  },
  "bearerToken": "auth-token"   // SSE/STREAMABLE_HTTP only
}
```
</CodeGroup>

### Environment Variables

Pass environment variables to STDIO servers:

```json
{
  "name": "TimeServer",
  "type": "STDIO",
  "command": "uvx",
  "args": ["mcp-server-time", "--local-timezone=America/New_York"],
  "env": {
    "TZ": "America/New_York"
  }
}
```

#### Environment Variable Interpolation

Use `${ENV_VAR}` syntax to reference environment variables at runtime:

```json
{
  "name": "ExampleServer",
  "type": "STDIO",
  "command": "uvx",
  "args": ["mcp-example"],
  "env": {
    "API_KEY": "${API_KEY}",
    "DEBUG": "true"
  }
}
```

**Benefits:**
- **Secure**: API keys and secrets aren't hardcoded in configs
- **Flexible**: Values resolved from container environment
- **Backward compatible**: Raw values still work as before

**How it works:**
- `${VAR_NAME}` gets replaced with `process.env.VAR_NAME` at runtime
- Missing variables log a warning but don't crash the server
- Secrets are automatically redacted in logs

### Authentication

For servers requiring authentication:

<CodeGroup>
```json STDIO with API Keys
{
  "env": {
    "API_KEY": "your-secret-key"
  }
}
```

```json Remote with Bearer Token
{
  "bearerToken": "your-bearer-token"
}
```
</CodeGroup>

## Managing MCP Servers

### Adding Servers

1. **Navigate** to MCP Servers in the MetaMCP dashboard
2. **Click** "Add Server" 
3. **Configure** the server details
4. **Test** the configuration
5. **Save** to make it available for namespaces

### Bulk Import/Export

MetaMCP supports bulk import and export of MCP server configurations for easy migration and backup.

#### Exporting Servers

Export all your configured MCP servers to a JSON file:

1. **Navigate** to MCP Servers in the dashboard
2. **Click** "Export JSON" button
3. **Choose** to either download the file or copy to clipboard

<Card title="Export Format" icon="code">
```json
{
  "mcpServers": {
    "HackerNews": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-hn"],
      "description": "Access HackerNews stories and comments"
    },
    "TimeServer": {
      "type": "stdio", 
      "command": "uvx",
      "args": ["mcp-server-time"],
      "env": {
        "TZ": "America/New_York"
      },
      "description": "Time and timezone utilities"
    },
    "RemoteAPI": {
      "type": "streamable_http",
      "url": "https://api.example.com/mcp",
      "bearerToken": "your-bearer-token",
      "description": "Remote MCP server via HTTP"
    }
  }
}
```
</Card>

#### Importing Servers

Import multiple MCP servers from a JSON configuration:

1. **Navigate** to MCP Servers in the dashboard
2. **Click** "Import JSON" button
3. **Paste** or type your JSON configuration
4. **Click** "Import" to add the servers

<CodeGroup>
```json STDIO Server Format
{
  "mcpServers": {
    "ServerName": {
      "type": "stdio",
      "command": "uvx",
      "args": ["package-name"],
      "env": {
        "API_KEY": "your-key"
      },
      "description": "Optional description"
    }
  }
}
```

```json SSE Server Format  
{
  "mcpServers": {
    "ServerName": {
      "type": "sse",
      "url": "https://api.example.com/sse",
      "bearerToken": "your-token",
      "description": "Optional description"
    }
  }
}
```

```json Streamable HTTP Format
{
  "mcpServers": {
    "ServerName": {
      "type": "streamable_http", 
      "url": "https://api.example.com/mcp",
      "bearerToken": "your-token",
      "description": "Optional description"
    }
  }
}
```
</CodeGroup>

<Note>
**Type Values (Case-Insensitive):**
- `"stdio"`, `"STDIO"`, `"std"` → STDIO
- `"sse"`, `"SSE"` → SSE  
- `"streamable_http"`, `"STREAMABLE_HTTP"`, `"streamablehttp"`, `"http"` → STREAMABLE_HTTP
</Note>

<Note>
**Import Behavior:**
- Servers with existing names will be **updated** with new configuration
- New servers will be **created**
- Invalid configurations will be **skipped** with error messages
- The import process shows success/failure counts
</Note>

<Tip>
Use bulk import/export for:
- **Environment migration** (dev → staging → production)
- **Team collaboration** (sharing server configurations)
- **Backup and restore** (configuration backups)
- **Quick setup** (deploying multiple servers at once)
</Tip>

### Idle Session Management

MetaMCP pre-allocates idle sessions for better performance:

<Card title="Cold Start Optimization" icon="zap">
- **Default**: 1 idle session per server
- **Configurable**: Adjust based on usage patterns
- **Auto-scaling**: Sessions created on demand
- **Cleanup**: Idle sessions recycled after timeout
</Card>

## Custom Dockerfile for Dependencies

If your MCP servers require additional dependencies beyond `uvx` or `npx`, you can customize the MetaMCP Dockerfile:

```dockerfile
FROM metamcp:latest

# Install Python dependencies
RUN pip install requests beautifulsoup4

# Install system packages
RUN apt-get update && apt-get install -y \
    curl \
    git \
    && rm -rf /var/lib/apt/lists/*

# Install Node.js packages globally
RUN npm install -g some-mcp-package
```

<Warning>
Custom dependencies increase the Docker image size and startup time. Consider using lightweight alternatives when possible.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion icon="triangle-alert" title="Server Won't Start">
    **Common causes:**
    - Missing dependencies (install via custom Dockerfile)
    - Incorrect command or arguments
    - Environment variables not set
    - Network connectivity issues (for SSE/Streamable HTTP)
    
    **Debug steps:**
    1. Check server logs in MetaMCP dashboard
    2. Test command manually in terminal
    3. Verify environment variables
    4. Check network connectivity
  </Accordion>

  <Accordion icon="clock" title="Slow Performance">
    **Optimization strategies:**
    - Increase idle session count for frequently used servers
    - Use local servers instead of remote when possible
    - Pre-install dependencies in custom Docker image
    - Configure appropriate timeout values
  </Accordion>

  <Accordion icon="shield" title="Authentication Issues">
    **Common problems:**
    - Expired API keys or bearer tokens
    - Incorrect environment variable names
    - Missing required headers
    - Rate limiting from external APIs
    
    **Solutions:**
    1. Refresh API keys/tokens
    2. Check server documentation for required auth
    3. Implement proper error handling
    4. Add retry logic with backoff
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Namespaces" icon="package" href="/en/concepts/namespaces">
    Group your MCP servers into organized namespaces
  </Card>
  
  <Card title="Set Up Endpoints" icon="link" href="/en/concepts/endpoints">
    Create public endpoints to access your servers
  </Card>
  
  <Card title="Add Middleware" icon="filter" href="/en/concepts/middleware">
    Transform and filter MCP requests and responses
  </Card>
  
  <Card title="Integration Guide" icon="plug" href="/en/integrations/cursor">
    Connect your configured servers to MCP clients
  </Card>
</CardGroup> 